fix(scripts): repair readiness-check doc gate — 3 defects, gate was unsatisfiable - #82

…unsatisfiable (#32)

Mirrors **hyperpolymath/Axiom.jl#82** into the vendored copy at
`packages/Axiom.jl`. The file here was **byte-identical** to `Axiom.jl`
`origin/main` (`sha256 4e8618eebc…`) before the change, so the same
patch applies verbatim.

`check_doc_alignment()` could never pass, for three separate reasons:

1. **Backticks caused command substitution** at `:98` — bash tried to
*execute* `from_pytorch("model.pt")`, emitted two syntax errors to
stderr, and printed the message with the crucial part **silently
deleted**. `bash -n` does not catch this; only shellcheck does.

2. **The assertion demanded a Python path the library rejects.** It
required README.adoc to document `from_pytorch("model.pt")`, which
`src/integrations/interop.jl:352` **explicitly throws** on —
`.pt`/`.pth`/`.ckpt` are Python pickles needing a PyTorch runtime. This
contradicted `interop.jl:98` (the `python3` shell-out was deliberately
removed) and `k9iser.toml:30` (*"Python interop is opt-in only, never a
hard dep"*). The README was already correct. Now asserts the supported
JSON descriptor form and **adds a guard** that the `.pt/.pth/.ckpt`
warning stays.

3. **A stale `ROADMAP.md` check** survived the `.md` → `.adoc`
migration. The repo ships only `ROADMAP.adoc`, so `rg` failed on a
missing file and `! rg` was permanently true, forcing `status=1`
regardless of documentation quality.

**Verified in this vendored context:** shellcheck **0** findings;
`check_doc_alignment` exits **0**; diff touches only
`packages/Axiom.jl/scripts/readiness-check.sh`.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CONTRIBUTING.md->CONTRIBUTING.adoc
MAINTAINERS.md->MAINTAINERS.adoc README.md->README.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CHANGELOG.md->CHANGELOG.adoc
CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc
CONTRIBUTING.md->CONTRIBUTING.adoc MAINTAINERS.md->MAINTAINERS.adoc
QUICKSTART.md->QUICKSTART.adoc SECURITY.md->SECURITY.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** MAINTAINERS.md->MAINTAINERS.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** MAINTAINERS.md->MAINTAINERS.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CHANGELOG.md->CHANGELOG.adoc
CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc
CONTRIBUTING.md->CONTRIBUTING.adoc MAINTAINERS.md->MAINTAINERS.adoc
README.md->README.adoc SECURITY.md->SECURITY.adoc TPCF.md->TPCF.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** claude.md->claude.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** README.md->README.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CHANGELOG.md->CHANGELOG.adoc
CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc
CONTRIBUTING.md->CONTRIBUTING.adoc MAINTAINERS.md->MAINTAINERS.adoc
README.md->README.adoc SECURITY.md->SECURITY.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CHANGELOG.md->CHANGELOG.adoc
MAINTAINERS.md->MAINTAINERS.adoc TEST-NEEDS.md->TEST-NEEDS.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** ABI-FFI-README.md->ABI-FFI-README.adoc
SECURITY.md->SECURITY.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** SECURITY.md->SECURITY.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** ABI-FFI-README.md->ABI-FFI-README.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CHANGELOG.md->CHANGELOG.adoc
CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc
CONTRIBUTING.md->CONTRIBUTING.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** ARCHITECTURE.md->ARCHITECTURE.adoc DEBT.md->DEBT.adoc
READINESS.md->READINESS.adoc TEST-NEEDS.md->TEST-NEEDS.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` migration moved `README.md` to `README.adoc` but
left every script reading the old name — `release/scripts/package.sh`,
`release/scripts/version.sh`, `scripts/ci/package.sh`.

⚠ Note the **variable-prefixed** forms (`"$PROJECT_ROOT/README.md"`,
`"${ROOT_DIR}/README.md"`), which a token-boundary rewrite misses — this
repo was deliberately held back from the estate sweep until they were
handled.

Two of these are `cp`/`sed -i` operations guarded by `2>/dev/null ||
true`, so they have been **failing silently**: the packaged artefact
simply had no README, and the version bump quietly stopped rewriting the
badge line.

Found by an estate-wide sweep of 454 repos: 56 such checks across 18
repos. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CHANGELOG.md->CHANGELOG.adoc
CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc
CONTRIBUTING.md->CONTRIBUTING.adoc
docs/PLUGIN_DEVELOPMENT.md->docs/PLUGIN_DEVELOPMENT.adoc
docs/QUICKSTART.md->docs/QUICKSTART.adoc docs/TPCF.md->docs/TPCF.adoc
MAINTAINERS.md->MAINTAINERS.adoc
PROJECT_SUMMARY.md->PROJECT_SUMMARY.adoc README.md->README.adoc
SECURITY.md->SECURITY.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com>

The `.md` → `.adoc` documentation migration moved these files but never
updated the scripts that **read** them, so every check naming a `.md`
has been operating on a file that no longer exists.

**Repointed:** CONTRIBUTING.md->CONTRIBUTING.adoc
MAINTAINERS.md->MAINTAINERS.adoc README.md->README.adoc

Three failure modes were in play across the estate, all fixed by the
same change:

| shape | effect |
|---|---|
| `check "X.md exists" "[ -f X.md ]"` | **hard fail** — can never pass |
| `[ -f X.md ] && ((doc_score++))` | silently scores lower |
| `if [ -f X.md ]; then …greps… fi` | **silent skip** — the block never
runs, so the gate reports success by *not checking* |

Labels are repointed too, so failure messages name the file actually
inspected. Where a script did `git add … X.md`, that is fixed as well —
it would have failed at release time.

Only tokens whose `.adoc` twin exists here were rewritten; anything
without a twin was left for separate triage.

Found by an estate-wide sweep of 454 repos: **56 such checks across 18
repos**. Same class as **hyperpolymath/Axiom.jl#82**.